<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Basics</title>
</head>
<body>
    <h3>Basic API</h3>
    <p>Those conversant with hibernate will know about SessionFactories, Sessions and Transactions. Here is a quick mapping of those classes to JPA2 api.
    <ul>
      <li>SessionFactory ---> EntityManagerFactory</li>
      <li>Session ---> EntityManager</li>
      <li>Transaction ---> EntityTransaction</li>
    </ul>
    The examples for various mappings will provide more details on JPA2 api.
    </p>
    <h3>Relationships Primer</h3>
      Here is a quick tour of relationships concepts and terminology. A grasp on these concepts will certainly be helpful in understanding various relationship mappings we'll be covering.
    <h4>Directionality</h4>
      Directionality provides means to reach each other for the two entities involved in a relationship. If only one entity maintains reference to other entity, the relationship is said to be <strong>unidirectional</strong>. If both entities maintain reference to each other the relationship is said to be <strong>bidirectional</strong>.
    <h4>Cardinality</h4>
      Cardinality denotes how many instances of each entity participate in a given relationship. For example, if we are modeling department to employee relationship. An employee can belong to only one department while a department can have many employee. Therefore, cardinality of employee side is said to be many and cardinality of department side is said to be one.
    <h4>Optionality</h4>
      For example, if we are mapping employee to project relationship, an employee may not be assigned to a project indicating he's on bench. Optionality is expressed in terms of cardinality being a range instead of a single value, and the range would begin with 0 or 1 depending on the optionality, 0 denoting optional nature and 1 being mandatory.
    <h3>Mappings Overview</h3>
    Based on the cardinality of the two entities participating in a relationship, there are four possible mappings -
    <ol>
      <li>One-to-one</li>
      <li>Many-to-one</li>
      <li>One-to-many</li>
      <li>Many-to-many</li>
    </ol>
    As we'll see in the examples, we have these four as annotations in JPA2 to map these relationships. At database level, relationships between tables are maintained using <em>foreign keys</em>. In JPA2, foreign keys are represented by <em>@JoinColumn</em> annotation.
    <h3>Entities and Value Types</h3>
    This is one of the most important concepts that, many times is not really well understood, giving rise to the anti-pattern of mapping components or value types as top level entities and using <em>cascading</em> to manage their lifecycle. Taking an example, suppose we are modeling blog entry and it's comments. The comments are owned by a particular blog entry and they don't have independent existence outside it. Entities and value types can be distinguished on the following two points -
    <ul>
      <li>Identity</li>
        Entities have their own database identity (Primary Key). They exist independently of any other entity. On the other hand, value types don't have an identifier property, because instances are identified through the owning entity.
      <li>Shared References</li>
        Entities can have shared references, i.e, two entity instances can refer to a single entity instance. But, value types cannot since they are owned by the owning entity. Taking the earlier example of blog entry and comments, a comment can only associated with a single blog entry and would be deleted if the owning blog entry is deleted.
    </ul>
    <h3>Bootstrapping configuration</h3>
    Hibernate looks for <em>hibernate.cfg.xml</em> file at the root of classpath for bootstrap configuration. JPA expects the bootstrapping configuration to be provided in <em>/META-INF/persistence.xml</em> file. Following is the <em>persistence.xml</em> file taken from the examples project.
    <p></p>
    <pre class="brush: xml">
      <persistence xmlns="http://java.sun.com/xml/ns/persistence"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
        version="2.0">
        <persistence-unit name="learningjpa2" transaction-type="RESOURCE_LOCAL">
        <!--  <provider>org.hibernate.ejb.HibernatePersistence</provider> -->
          <properties>
            <property name="javax.persistence.jdbc.driver" value="com.mysql.jdbc.Driver"></property>
            <property name="javax.persistence.jdbc.user" value="root"></property>
            <property name="javax.persistence.jdbc.password" value="root"></property>
            <property name="javax.persistence.jdbc.url" value="jdbc:mysql://localhost/learningjpa2"></property>

            <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLInnoDBDialect"></property>
            <property name="hibernate.hbm2ddl.auto" value="create"></property>
            <property name="hibernate.show_sql" value="true"></property>
            <property name="hibernate.format_sql" value="true"></property>
            <property name="hibernate.use_sql_comments" value="true"></property>
            <property name="hibernate.max_fetch_depth" value="3"></property>
          </properties>
        </persistence-unit>
      </persistence>
    </pre>
    <p></p>
    <p>
      A few things to mention about the configuration above -
      <ul>
        <li>Hibernate is being used as persistence provider.</li>
        <li>The database connection properties such as <em>jdbc.driver</em> have been standardized in JPA2. In JPA1, you needed to use vendor specific properties for this purpose.</li>
        <li>Vendor-specific properties such as <em>hibernate.hbm2ddl.auto</em> are needed to provide custom configuration details not standardized in JPA2.</li>
        <li>Autoscanning of classpath for entities has been standardized only in Java EE environment in JPA2. But Hibernate makes this very useful feature available in Java SE too, thereby get rid of the need to mention every hbm file or annotated class name in the configuration.</li>
        <li>If Hibernate is being used as the only persistence provider in an application, there is no need to provide explicit <em>provider</em> property in <em>persistence.xml</em> as shown by the commented out property in the above configuration. </li>
      </ul>
    </p>
</body>
</html>